Subject: Set_Queue_Callback_Function

From: "Chung-Huy Chen (254-4827 T/L 444)" <[email-masked]>
Date: Tue, 29 Jun 93 11:45:35 EDT

Referenced note: 28 June 1993 15:12:44 from <[email-masked]>

A program uses the Set_Queue_Callback_Function call to associate the
following three parameters with a queue:

   1) callback_function: a routine that is invoked when an outstanding
      operation completes.

   2) user_field: an application data that is an input to the associated
      callback function.  CPI-C does not interpret the content of this
      field.  The user gets back exactly what he specified.

   3) callback_info: an application data that may be passed to the
      associated callback function.  CPI-C can parse this data.
      The user may or may not get all the supplied data back.

In the June's CIW, a few Windows' experts concluded that a sensible way
of using these three parameters in Windows is as follows:

   1) callback_function: <nil>
   2) user_field: <nil>
   3) callback_info: a pointer to
                         MSG struct {
                             Win_Handle,
                             Message,
                             wparm,
                             lparm,
                             ...
                         };
     When an outstanding operation completes, CPI-C invokes a Windows
     call
           PostMessage(Win_Handle, Message, wparm, lparm);

     using the first four elements in the MSG struct pointed to by
     callback_info.
     (This is the reason why callback_info was added.)

On the other hand, a possible mapping to Unix systems is as follows:

   1) callback_function: a user-defined completion handler (playing
      the same role as a signal handler)
   2) user_field: a signal id (either SIGUSR1 or SIGUSR2)
   3) callback_info: ? (an address to the return parameters)

Our goal is to promote the programs' portability between the like
systems by:

   -identifying the essential information for each platform of interest
    (e.g., the use of MSG struct as callback_info in Windows and the
    use of signal id as user_field in Unix systems in the above-mentioned
    ideas).
   -documenting recommended usage for each platform (e.g., recommended
    values for elements of MSG).

Notice that the likely mappings mentioned above (both for Windows and
for Unix) are ideas.  All platforms are encouraged to submit a proposed
text of recommendations for their users to be included in the CPI-C
Architecture Spec. (The text should be prepared as a usage note to the
Set_Queue_Callback_Function call.)  The NB SIG will first review the
submissions and later request CIW to formally adopt the recommendations
when CP is granted.

By reading Steve Berl's description for the Mac environment, I conclude
the following:

   1) callback_function: completion_handler( /input/ user_field);
   2) user_field: pointer to a data structure
   3) callback_info: <nil>

Steve, please make any corrections or adjustments.

Chung-Huy Chen